Inside Macintosh: Macintosh Toolbox Essentials

Previous | Chapter Top | Chapter Contents | Next

The Color Window Record

The Window Manager maintains a window record or color window record for each window on the desktop.

The Window Manager supplies functions that let you access the window record as necessary. Your application seldom changes fields in the window record directly.

The CWindowRecord data type defines the window record for a color window. The CWindowPeek data type is a pointer to a color window record. The first field in the window record is in fact the record that describes the window's graphics port. The CWindowPtr data type is defined as a CGrafPtr , which is a pointer to a graphics port (in this case, the window's graphics port).

When Color QuickDraw is not available, you can create monochrome windows using the parallel data types WindowRecord , WindowPeek , and WindowPtr , described in "The Window Record"

For compatibility, the WindowPtr and WindowPeek data types can point to either a color window record or a monochrome window record. You use the WindowPtr data type to specify a window in most Window Manager functions, and you can use it to specify a graphics port in QuickDraw functions that take the GrafPtr data type. Note that you can access only the fields of the window's graphics port, not the rest of the window record, through the WindowPtr and CWindowPtr data types. You use the WindowPeek and CWindowPeek data types in low-level Window Manager functions and in your own functions that access window record fields beyond the graphics port.

The functions that manipulate color windows get color information from the window color tables and the auxiliary window record described in the sections "The Window Color Table Record" and "The Auxiliary Window Record" .

port

The graphics port record that describes the graphics port in which the window is drawn.

The graphics port record, which is documented in Inside Macintosh: Imaging, defines the rectangle in which drawing can occur, the window's visible region, the window's clipping region, and a collection of current drawing characteristics such as fill pattern, pen location, and pen size.

windowKind

The class of window--that is, how the window was created.

The Window Manager fills in this field when it creates the window record. It places a negative value in windowKind when the window was created by a desk accessory. (The value is the reference ID of the desk accessory.) This field can also contain one of two values described in "Window Kinds" indicating how the window was created: dialogKind or userKind .

visible

A Boolean value indicating whether or not the window is visible. If the window is visible, the Window Manager sets this field to true ; if not, false . Visibility means only whether or not the window is to be displayed, not necessarily whether you can see it on the screen. (For example, a window that is completely covered by other windows can still be visible, even if the user cannot see it on the screen.)

hilited

A Boolean value indicating whether the window is highlighted--that is, drawn with stripes in the title bar. Only the active window is ordinarily highlighted. When the window is highlighted, the hilited field contains true ; when not, false .

goAwayFlag

A Boolean value indicating whether the window has a close box.

The Window Manager fills in this field when it creates the window according to the information in the 'WIND' resource or the parameters passed to the function that creates the window.

If the value of goAwayFlag is true , and if the window type supports a close box, the Window Manager draws a close box when the window is highlighted.

spareFlag

A Boolean value indicating whether the window type supports zooming. The Window Manager sets this field to true if the window's type is one that includes a zoom box ( zoomDocProc , zoomNoGrow , or even modalDBoxProc + zoomDocProc ).

strucRgn

A handle to the structure region, which is defined in global coordinates. The structure region is the entire screen area covered by the window--that is, both the window contents and the window frame.

contRgn

A handle to the content region, which is defined in global coordinates. The content region is the part of the window that contains the document, dialog, or other data; the window controls; and the size box.

updateRgn

A handle to the update region, which is defined in global coordinates. The update region is the portion of the window that must be redrawn. It is maintained jointly by the Window Manager and your application. The update region excludes parts of the window that are covered by other windows.

windowDefProc

A handle to the definition function that controls the window.

There's no need for your application to access this field directly.

In Macintosh models that use only 24-bit addressing, this field contains both a handle to the window's definition function and the window's variation code. If you need to know the variation code, regardless of the addressing mode, call the GetWVariant function (GetWVariant) .

dataHandle

Usually a handle to a data area used by the window definition function.

For zoomable windows, dataHandle contains a handle to the WStateData record, which contains the user state and standard state rectangles. The WStateData record is described in "The Window State Data Record" .

A window definition function that needs only 4 bytes of data can use the dataHandle field directly, instead of storing a handle to the data. The window definition function that handles rounded-corner windows, for example, stores the diameters of curvature in the dataHandle field.

titleHandle

A handle to the string that defines the title of the window.

titleWidth

The width, in pixels, of the window's title.

controlList

A handle to the window's control list, which is used by the Control Manager. (See the chapter "Control Manager Reference" in this book for a description of control lists.)

nextWindow

A pointer to the next window in the window list, that is, the window behind this window on the desktop. In the window record for the last window on the desktop, the nextWindow field is set to nil .

windowPic

A handle to a QuickDraw picture of the window's contents. The Window Manager initially sets the windowPic field to nil . If you're using the window to display a stable image, you can use the SetWindowPic function (SetWindowPic) to place a handle to the picture in this field. When the window's contents need updating, the Window Manager then redraws the contents itself instead of generating an update event.

refCon

The window's reference value field, which is simply storage space available to your application for any purpose. The sample code in this chapter uses the refCon field to associate a window with the data it displays by storing a window type constant in the refCon field of alert and dialog window records and a handle to a document record in the refCon field of a document window record.

The close box, drag region, zoom box, and size box are not included in the window record because they don't necessarily have the formal data structure for regions as defined in QuickDraw. The window definition function determines where these regions are.

Previous | Chapter Top | Chapter Contents | Next